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(54) SIM manager API 



(57) A SIM Manager is disclosed that accesses 
functionality contained within a GSM-type telephone 
SIM by combining functionality of a plurality of asynchro- 
nous RIL functions into a single synchronous application 
programming interface. A first dynamic-link: library ..re- 
ceives a function call for performing a selected function 
from an application operating in a GSM-type telephone 
device. The first dynamic link library is preferably a stub 
dynamic link library to. which applications^ link., links to 
the application and initiates a process^ thread corre- 
sponding to the received function call, thereby blocking 
all subsequently received calls until the received func- 
tion call for the selected function is complete. A second 



-dynamic link library contains at least one application 
programming interface corresponding to the selected 
function. Each application programming interface corre- 
sponds to- the selected function within the second dy- 
namic linkiibrary links to a radio interface layer of the 
GSM-type telephone device for performing the selected 
function. The second dynamic link library is loaded by 
the first dynamic link library when the first dynamic link 
library receives the function call. The second dynamic 
link library initiates' a process thread corresponding to 
the received function call and blocks all subsequently 
received calls until the received function call for the se- 
lected function is complete. 
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storage device 111 has.been illustrated in Figure 1 . The 
logical connections depicted in Figure 1 include a local 
area network (LAN) 112 and a wide area network (WAN) 
113. Such networking environments are commonplace 
in offices, enterprise-wide computer networks, intranets 
and the Internet 

[0015] When used in a LAN networking environment, 
computer 100 is connected to local network 112 through 
a network interface or adapter 114. When used in a WAN 
networking environment, personal computer 100 typi- 
cally includes a modem 115 or other device for estab- 
lishing a communications over wide area network 113, 
such as the Internet. Modem 115, which may be internal 
or external, is connected to system bus 130 via serial 
port interface 106. In a networked environment, pro- 
gram modules depicted relative to personal computer 
100, or portions thereof, may be stored in the remote 
memory storage device. 

[0016] It will be appreciated that the network connec- 
tions shown are exemplary and other techniques for es- 
tablishing a communications link between the comput- 
- ers can be used. The existence of any of various well- 
known p'rotoco Is, such- as TCP/IP, Ethernet, FTR.HTTP 
_and the jike, is presumed, and the system can be oper- . 
ated in axHent-sen/er cohftgu ration i to. Rerm[t'aJtfMr^:^s 
^retrieye we b pages;from a web-,based;sery erv Any ofva r-^- z 
jo'usconWntiona^ 

^pi^anjpuiate data^qn wetrpages^^' " " " 
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^jica^progr^n^ 

~ageT£pl>t^^ 
-contained withina GSM-type telephone SIM card r such^^ 
_ as access to phonebook entries, passwords, file access * ~; 
_ and massage? storage. Additionally, W S IM^Man^ger^^ 
..API structure_of Jhe present i^ention combines func-^^ 
lioi^ityofseveTaTasiynchron ^V 

synchronous API so that "th^ SIM state is not reset be-~"t 
neath.the SIM Manager, thereby allowing information to 
be safely read or written the SIM card without the pos- 
sibility of another application invalidating the results. Ad- 
ditionally; applications calling the API set of the present 
invention are not required to have specific knowledge 
regarding conventional RIL APIs. 
[0018] The present invention includes a set of two Dy- 
namic Link Libraries (DLLs) that provide APIs for ac- 
cessing SIM functionality and notifies a calling applica- 
tion when the state of the elements contained in the SIM 
card change. The first DLL is a stub DLL (simmgr.dll) 
that is a small DLL to which applications link. The first 
DLL loads a second DLL (smgreal.dll) that includes an 
implementation of APIs for accessing SIM functionality 
and for providing notifications. The two-DLL architecture 
provides that when a cellular phone does not have a SIM 
card, such as a conventional CDMA-type phone, the 
second DLL can be removed and the ROM size signifi- 
cantly reduced without adversely impacting applications 
using the SIM Manager. 

[0019] The API set of the present invention can be di- 



vided into the following five classes of APIs: 

1) Phone book APIs for reading and writing phone- 
book entries on the SIM; 

2) Locking APIs for locking and unlocking the 
phone, and changing the SIM password; 

3) Message APIs for reading and writing text SMS 
messages on the SIM card; 

4) Record APIs for reading and writing records (or 
files) on the SIM card; and 

• 5) Miscellaneous APIs for Initializing SIM Manager 
and determining the capabilities of the SIM card. 

[0020] A calling application can also request to be n o-. 
tified whenever the status of the SIM card changes 
roughly corresponding to the five classes of APIs. For 
example, notifications can be sent to an application 
whenever a SIM phonebook entry is changed, whenev- 
er an SMS message has changed, etc. 
[0021] To illustrate the present invention, Figure 2 
shows an exemplary signal-flow diagram 200 between 
selected layers of a.GSM-type telephone device having > 
a S IM_card for-readirig a ph^nebpoyentry^c^ording to 
~lhe 7 pWent\inyention. Figure ^shoW^ Uie:structural re-^ 
lation^p between " S 'MJ Z ' 

■Mtffag^API^ 
=lftelSa^ 

Zglfcoli^ W 



^HRESULT- ^Simlnitiaiiz^(DWdRp~dwFlags, SIM-; 
^At^BACKypfnC^ 
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"[0022] - "STrhinitialize provided f 'cillback^function 'flag- 
: (lpfnCallBack) that is used for indicatingthat notification -J 
is desired when the SIM state changes. A dwParam pa- * 
rameter can also be specified that is passed to the call- 
back function. When notifications are not desired, dw- 
Flags should be set to 0, and the second and third pa- 
rameters of Simlnitialize are ignored. IphSim is an out 
parameter that gets set with a handle to an HSIM when 
SIM Manager 202 is successfully initialized. 
[0023] When application 201 calls the Simlnitialize 
API. the first DLL (simmgr.dll) 204 attempts to load the 
second.DLL (smgrreal.dll) 205. In the situation when 
simmgrdll 204 is unable to load smgrreal.dll 205, sinv 
mger.dll 204 immediately returns an error code 
SIM_E_NOSIM to application 201. When simmgr.dll 
204 is able to load smgrreal.dll 205. simmgr.dll 204 calls 
into smgrreal.dll 205 to perform the actual initialization 
operation. Second DLL simgrreal.dll 205 initializes RIL 
203 and obtains an HRIL handle for making subsequent 
RIL calls. The initialization function also creates a glo- 
bally named event handle that is used for synchronizing 
SIM Manager calls, as described beloyv. 
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[0024) i In the situation whenan application desires to f 
receive callback notifications, a second thread is set up . 
that is able to dispatch the notifications to the calling ap- 
plication. A second thread is necessary so that the call-, 
ing application does not block other processes while 
waiting in a callback function. Most notifications are re- 
ceived directly from RIL 203, but the present invention 
also provides a.f We refresh notification that is received 
from a SIM toolkit process when the SIM supports SIM 
toolkit applications (not shown). When the SIM supports 
SIM toolkit applications, the present invention registers 
. with the SIM Toolkit process so that file refresh notifica- 
tions will be received. . 

[0025] After JSimlnitiajize has been successfully 
called, the SimReadPhpnebookEntry APJ is called for 
reading a phonebook entry, as shown at 210 in Figure 
2. The SimReadPhoneBookEnjtry API is defined as fol- , 
lows: : 

HRESULT SimReadPhonebpokEntry (HS.IM hSim. 
DWORD dwlocation, DWORD. dwlndex* JLPSIM- . 
. PHONEBOOKENTRY 1 pPhonebpokEntry) . 

[0026] The SimReadPhphebookEntry ^ includes ~ a 
HSIM parameter that is used for passing the HSIM re- 
ceived from tb^Simlnitialize call.. The dwlocation pa- . 
rameter is usedjfor passing 4)P^!^^JI^P 0 ^^i 0 T: 
the SIMjphonebiook location thaj isjo b^cc§s|^^he^ 
dwlndex^ 
rto- an indexy^ithin^^ 

with the phonebook entry. . r -^~r : ^^ 

[0027] The SimReadPhohebookEntry API "first at- ■ 
tempts at 211 to obtain a globally named jepgnt handle 
that -was created dunng:the Sim Into 
by erisuring that no two pTpcessesldxrjthe •s^terrTO.e., : 
another application) will be able to calljnto a SIM Man- 
ager API at the same time. In the event that two pros- 
esses are calling APIs at the same time, one of the call- 
ing processes will block until the other process has com- 
pleted and released the event for the other process to 
continue. 

[0028] When a global named event handle has been 
obtained, the current phonebook storage location is de- 
termined. The SIM Manager of the present invention is 
able to monitor of the current phonebook storage loca- 
tion because the SIM Manager receives notifications 
from RIL whenever the storage location has changed by 
any process on the system. When SIM Manager 202 
has not yet received this particular notification .(because 
the location has not been changed), or the location is 
different than the one that the calling application has re- . 
quested, SIM Manager 202 calls the RIL function. 
RIL_SetPhonebookStorageLocation. as shown at 212. 
Because this particular RIL function is an asynchronous 
API, SIM Manager 202 waits on a second event at 213. 
so that the process is blocked until RIL 203 has returned 
a result. Preferably, the present invention stores- the cur- 



rent phonebook storage location and checks the current 
phonebook storage location before first calling this 
asynchronous RIL API is purely for performance relia- 
; bility reasons. The present invention can; alternatively, 
5 blindly call the RIL_SetPhonebookStorageLocation RIL 
API without a check. 

[0029] AfterSIM Manager 202 has received confirma- 
tion from RIL 203 that the phonebook storage location 
has changed to the desired phonebook, the 

10 RIL_ReadPhonebookEntry API is called at 214. An im- 
portant aspect about the RIL_ReadPhonebookEntry 
API is that only an index is needed, not a storage loca- 
tion, because this API reads from the currently selected 
storage location. Because SIM Manager 202 has just 

15 set the storage location (or verified the storage location 
is set to the desired storage location), and because all 
processes must access the SIM via the SIM Manager 
APIs, thereby blocking any other processes calling S IM 
Manager 202 until the current API is complete, the 

20 present invention is abletoguaranteethatthecorrection 
storage location is being read. 
' [0030] Once SIM Manager 202 has received the re- 
sult aL2i 5, the handle is released so other processes 
" calling S(M Manager 202 can continue; and the result is 

25 returned to the calling application at 216. The internal 
RIL handle is deinitiajized and any memory used by SIM 

-^:ManageK20lisifceedby calling th e'Sim Peinitialize API, 

^J^sipjldwsE^^^t- -.-.v" r ~ ' : --f ".---' ! - 1 - 
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^ T : {0Q31]- ' Generally speaking, the other APIs of the 
-present invention follow the same logical flow as in this 
example, f hat is, the other APIs of the present invention 

jsVfirstpb^^ 

-^tiple^R^ * 
*7~-[0032] S 1 */!!^- tee r "ffr«80iil fihventfon " has been de- 
scribed in connection with the illustrated embodiments, 
it will be appreciated and understood that modifications 
may be made without departing from the true spirit and 
scope of the invention. 



40 



Claims 



45 



A SIM Manager for accessing functionality con- 
tained within a GSM-type telephone SIM. the SIM 
Manager comprising: . 

so a first dynamic link library receiving a function 

call for performing a selected function from an 
application operating in a GSM-type telephone 
device; and 

a second dynamic link library containing at least 
55 . one application programming interface corre- 
sponding to the selected function, each appli- 
cation programming interface corresponding to 
the selected function linking to a radio interface 
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2. 



3. 



layerof the GSM-type telephone device for per- 
forming the selected function, the second dy- 
namic link library being loaded by the first dy- 
namic link library when the first dynamic link li- 
- brary receives the function call, the second dy- 
. naniic link library initiating a process thread cor- 
responding to the received function call and 
blocking all subsequently received calls until 
the received function call for the selected func- 
tion is complete. 

The SIM Manager according to claim 1 , wherein the 
first dynamic link library is a stub dynamic link li- 
brary. 

the SIM Manager according to claim 1 , wherein the 
SIM contains a phonebook having at least one en- 
try, and 

wherein the SIM Manager sends a notification 
to at least one selected application when an entry 
in the SIM phonebook changes. . t : : 
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15 



20 





:^r|^The 

"SIM Manager sehds-a-notification to at least-one.. ~ 
f v — ~ selected r appjicjti;on when a message contajned in /^^ 
\ ; ibe GSM^peJ^gphpQe^lM change s. -^^gg sj^a 

Mg[b£thj^^^^ i^^f^A^Q 

" the SIM = ManVg^acc»rdin"g to claim i, vvKerejn— ^ 

when the fi^ 
_ticml<g>llto]^ 

J^<^~n^ 

I ^'tfates a second. process thread &Aa(%e^^mgj?Q 
application'does not block' other applications run-. 
ning on the GSM-type telephone device. 

40 

7. The SIM Manager according to claim 6, wherein the 
SIM Manager receives a notification directly from 
the radio interface layer. 

8: The SIM Manager according to claim 6, wherein the 
SIM Manager receives a notification from a SIM 
toolkit process. 

9. The SIM Manager according to claim 1 . wherein the 
received function call is for performing an initializa- 
tion of a SIM card, and 

wherein when the first dynamic link library re- 
ceives the function call for performing the initializa- 
tion function, the first dynamic link library sends an 
initialization call to the second dynamic link library 
for initializing the SIM card. 

10. The SIM Manager according to claim 9, wherein 



45 



when the second dynamic link iibraiy in'rtfafizes the 
SIM card, the second dynamic link library obtains 
an HRIL handle for making subsequent calls to the 

ril, 

11. The SIM Manager according to claim 10, wherein 
the initialization function creates a globally-named 
event handle for synchronizing calls from a plurality 
of applications operating in the GSM-type tele- 
phone device to the SIM Manager. 

12. The SIM Manager according to claim 1, wherein 
when the first dynamic link library receives the func- 
tion call for performing the selected function, the 
second dynamic link library attempts to obtain a glo- 
bally named event handle that was created during 
an initialization process of a SIM card. 

13. The SIM Manager according to claim 12, wherein 
when the function call for performing the selected 
function is complete, the second dynamic link li- 
brary releases the globally-named event handle. 

14. A method for communicating between an applica- 
_. Jion layefwithiri a GSM-type telephone device and_ 

--. ^. a radio interface lay 

^ISfece^ a select- 

l^P^^d; "function at;a first-dynamic linkjibrary from 
*ris^fipjj"c^n^opera^g-in the. GSM-type ^ tele- 

^S^ Tphone device; ~ ~ " ^. r---— - 

w "loading a.second dynamic link library when the 
- . ^ function pall.is received ; * 
~*~--1nTtiating a process thread corresponding to the" 
"ri^r^elveli.function call; = £ ^- '- ; '^w 

blocking- all subsequently received function 
calls at the second dynamic link library until the 
received function call for the selected function 
is complete; and 

issuing a function call to a second dynamic link 
library corresponding to the selected function, 
the second dynamic link library containing at 
least one application programming interface 
corresponding to the selected function, each 
application programming interface correspond- 
ing to the selected function linking to a radio in- 
terface layer of the GSM-type telephone device 
for performing the selected function. 
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15. The method according to claim 14. wherein the first 
dynamic link library is a stub dynamic link library. 

16. The method according to claim.14, wherein the RIL 
includes a SIM containing a phonebook having at 
least one entry, and . 

the method further comprising a step of send- 
ing a notification to at least one selected application 



11 
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. ; %: vvhen an entry jh, the SIM phonebook changes. 

17. The method according to claim 14, further compris- 
ing a step of sending a notification to at least one 
selected application when a message contained in 
the GSM-type telephone SIM changes. 

-18. The method according to claim 14, further compris- 
ing a step of sending a notification to at least one 
selected application when a message is received 
by the GSM-type telephone SIM. 

19. The metho<fcaccqrding to claim 14, further compris- 
ing a step of initiating a second process thread by 
the second dynamic link Jibrary so that the calling 
application does, not block other applications run- 
ning on the GSM-type telephone device when the 
first dynamic link library receives a function call from 
the application for performing a notification function. 

20. The method according to claim.1 9, further. compris- 
ing a step of receiving a notification directly from.the 

:_ radio interf^ Layer.?^ v _ ^ iT^f^^rS -zSj^ 

21. The methocfcaccording taclaim .19, furtherjbompris- 
-ing a step^f rec"eivjng r a notrfiwtio^fr^ra£SIIVb; 

; w^lkit^rocessif: 
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. selected function is complete. .. 

27. A computer-readable medium haying computer- ex- 
ecutable instructions for performing steps comp ris- 
ing 1 ■ 

receiving a function call for performing a select- 
ed function at a first dynamic link library from 
an application operating in the GSM-type tele- 
phone device; 

loading a second dynamic link library when the 
function call is received; 
initiating a process thread corresponding to the 
received function call; 

blocking all subsequently received function 
calls at the second dynamic link library until the 
received function call for the sefected function 
is complete; and 

issuing a function call to a second dynamic link 
library corresponding to the selected function, 
the second dynamic link iibrary containing at 
: Jeast one application programming interface 
-TrL" cprresjpqnd[ng to the selected -function, each 
7- ; application programming interface correspond* 
jng to the'selected function linking to.a radio in- 
-^tsrface layerof the GSM-type teteph^he device 



^Jr^lyna mic^in H[&rary% ~" ■ ^ "^^SS^fflS 



rceivedfuir^5<^^ 



% ^th^meth6d:fiTithe7*5q^f& 

-ing an initialization call;to the secpnd^dyriamic Hnk~- 
library-fonnitializing.the.SIM 'cardw^n^eifirstdy-v: 

"namic^.ink lilfrary receiras^e^^^ 

_ fon^in^lTe'initiaiization^ 
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23. The method according to claim 22, further compris- 
ing a step of obtaining an HR1L handle for making 
subsequent calls to the RIL when the second dy- *o 
namic link library initializes the SIM card. 

24. The method according to claim 23, wherein the in- 
itialization function creates a globally-named event 
handle for synchronizing function calls from a plu- 45 
raiity of applications operating in the GSM-type tel- 
ephone device. 



25. The method according to claim 14, further compris- 
ing a step of attempting to obtain a globally-named so 
event handle that was created during an initializa- 
tion process of a SIM card when the first dynamic 32. 
link library receives the function call for performing 
the selected function. 



:29^ 7 The^mputer-reaclable medium according ttfclaim 
^^\y^hemn ^eJ^L includes a-SIM containing a 

---- : comprising a step of sending a nbtificaUoh to at least " 
one selected application when an entry in the SIM 
phonebook changes. . 

30. The computer-readable medium according to claim 
27, wherein the SIM Manager sends a notification 
to at ieast one selected application when a mes- 
sage contained in the GSM-type telephone SIM 
changes. 

31. The computer-readable medium according to claim 
27, wherein the SIM Manager sends a notification 
to at least one selected application when a mes- 
sage is received by the GSM-type telephone SIM. 



.55 



26. The method according to claim 25, further compris- 
ing a step of releasing the globally-named event 
handle the received function call for performing the 



The computer-readable medium according to claim 
27, further comprising a step of initiating a second 
process thread by the second dynamic link library 
so that the calling application does not block other 
applications running on the GSM-type telephone 
device when the first dynamic, link library receives 
a function call from the application for performing a 
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notification function. 

33. The computer-readable medium according to claim 
32, further comprising a step of receiving a notifica- 
tion directly from the radio interface layer. 5 

34. The computer-readable medium according to claim 
32, further comprising a step of receiving a notifica- 
tion from a SIM toolkit process. 

10 

35. The computer-readable medium according to claim 
27, wherein the received function call is for perform- 
ing an initialization of a SIM card, 

the method further comprising a step of send- 
ing an initialization call to the second dynamic link 15 
library for initializing the SIM card when the first dy- 
namic lirik.library receives the function call for per- . 
forming the initialization function. 

36. The computer-readable medium according to claim 20 
35, further comprising a step of obtaining an HRIL 

- handle for making subsequent calis to the RIL when 

the second^ - - 



card. 



25. 




~37t the cdmputejtrf^ 
fe^"^36 ^wherein th^jnftjajizajjoiifunptionx 
3r ^bally-nar^d^^ 

^ ;V <ti6^ 

~ ^ .1 ^ 

V - ' 27, further comprising a~step of attempting jo obtaihr : 
^ a^glpj^ajly^a^edreyent h 

: ^d^ng:a_nij^^ 

call for ^perfofmhig the selected function.-- *• 

39. The computer-readable medium according to claim 
: 38, further comprising a step of releasing the glo- *o 
bally-named event handle the received function call 
for performing the selected function is complete. 
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